package com.quaidi.smartlocker.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.quaidi.smartlocker.dto.PackageDepositRequest;
import com.quaidi.smartlocker.dto.PackagePickupRequest;
import com.quaidi.smartlocker.entity.ExpressPackage;

/**
 * 快递包裹Service接口
 * 
 * @author QuaiDi
 * @since 2025-08-26
 */
public interface ExpressPackageService extends IService<ExpressPackage> {

    /**
     * 存放快递包裹
     * 
     * @param request 存放请求
     * @return 存放结果（包含取件码）
     */
    ExpressPackage depositPackage(PackageDepositRequest request);

    /**
     * 取件
     * 
     * @param request 取件请求
     * @return 取件结果
     */
    ExpressPackage pickupPackage(PackagePickupRequest request);

    /**
     * 根据快递单号查询包裹
     * 
     * @param trackingNumber 快递单号
     * @return 包裹信息
     */
    ExpressPackage getByTrackingNumber(String trackingNumber);

    /**
     * 根据取件码和电话查询包裹
     * 
     * @param pickupCode 取件码
     * @param recipientPhone 收件人电话
     * @return 包裹信息
     */
    ExpressPackage getByPickupCodeAndPhone(String pickupCode, String recipientPhone);

    /**
     * 仅根据取件码查询包裹
     * 
     * @param pickupCode 取件码
     * @return 包裹信息
     */
    ExpressPackage getByPickupCode(String pickupCode);
}